  <!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="generator" content="pandoc" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
    <title>GTK 4 tutorial</title>
    <style>
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}
      span.underline{text-decoration: underline;}
      div.column{display: inline-block; vertical-align: top; width: 50%;}
      div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
      ul.task-list{list-style: none;}
      pre{overflow: visible;}
      pre > code.sourceCode { white-space: pre; position: relative; }
      pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
      pre > code.sourceCode > span:empty { height: 1.2em; }
      code.sourceCode > span { color: inherit; text-decoration: inherit; }
      div.sourceCode { margin: 1em 0; }
      pre.sourceCode { margin: 0; }
      @media screen {
      div.sourceCode { overflow: auto; }
      }
      @media print {
      pre > code.sourceCode { white-space: pre-wrap; }
      pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
      }
      pre.numberSource code
        { counter-reset: source-line 0; }
      pre.numberSource code > span
        { position: relative; left: -4em; counter-increment: source-line; }
      pre.numberSource code > span > a:first-child::after
        { content: counter(source-line);
          position: relative; left: -1em; text-align: right; vertical-align: baseline;
          border: none; display: inline-block;
          -webkit-touch-callout: none; -webkit-user-select: none;
          -khtml-user-select: none; -moz-user-select: none;
          -ms-user-select: none; user-select: none;
          padding: 0 4px; width: 4em;
          color: #aaaaaa;
        }
      pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
      div.sourceCode
        {   }
      @media screen {
      pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
      }
      code span.al { color: #ff0000; font-weight: bold; } /* Alert */
      code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
      code span.at { color: #7d9029; } /* Attribute */
      code span.bn { color: #40a070; } /* BaseN */
      code span.bu { } /* BuiltIn */
      code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
      code span.ch { color: #4070a0; } /* Char */
      code span.cn { color: #880000; } /* Constant */
      code span.co { color: #60a0b0; font-style: italic; } /* Comment */
      code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
      code span.do { color: #ba2121; font-style: italic; } /* Documentation */
      code span.dt { color: #902000; } /* DataType */
      code span.dv { color: #40a070; } /* DecVal */
      code span.er { color: #ff0000; font-weight: bold; } /* Error */
      code span.ex { } /* Extension */
      code span.fl { color: #40a070; } /* Float */
      code span.fu { color: #06287e; } /* Function */
      code span.im { } /* Import */
      code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
      code span.kw { color: #007020; font-weight: bold; } /* Keyword */
      code span.op { color: #666666; } /* Operator */
      code span.ot { color: #007020; } /* Other */
      code span.pp { color: #bc7a00; } /* Preprocessor */
      code span.sc { color: #4070a0; } /* SpecialChar */
      code span.ss { color: #bb6688; } /* SpecialString */
      code span.st { color: #4070a0; } /* String */
      code span.va { color: #19177c; } /* Variable */
      code span.vs { color: #4070a0; } /* VerbatimString */
      code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
      div.sourceCode { margin: 10px; padding: 16px 10px 8px 10px; border: 2px solid silver; background-color: ghostwhite; overflow-x:scroll}
      pre:not(.sourceCode) { margin: 10px; padding: 16px 10px 8px 10px; border: 2px solid silver; background-color: ghostwhite; overflow-x:scroll}
      table {margin-left: auto; margin-right: auto; border-collapse: collapse; border: 1px solid;}
      th {padding: 2px 6px; border: 1px solid; background-color: ghostwhite;}
      td {padding: 2px 6px; border: 1px solid;}
      img {display: block; margin-left: auto; margin-right: auto;}
      figcaption {text-align: center;}
    </style>
  </head>
  <body style="padding-top: 70px;">
    <div class="container">
    <nav class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
      <div class="container-fluid">
        <span class="navbar-brand">Gtk4 tutorial</span>
        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
          <span class="navbar-toggler-icon"></span>
        </button>
        <div class="collapse navbar-collapse" id="navbarSupportedContent">
          <ul class="navbar-nav me-auto mb-2 mb-lg-0">
            <li class="nav-item">
<a class="nav-link" href="index.html">Home</a>
</li>

            <li class="nav-item">
<a class="nav-link" href="sec8.html">Prev: section8</a>
</li>

            <li class="nav-item">
<a class="nav-link" href="sec10.html">Next: section10</a>
</li>

          </ul>
        </div>
      </div>
    </nav>
<h1 id="gtkbuilder-and-ui-file">GtkBuilder and UI file</h1>
<h2 id="new-open-and-save-button">New, Open and Save button</h2>
<p>We made very simple editor in the previous section. It reads files at
the start and writes them out at the end of the program. It works, but
is not so good. It would be better if we had “New”, “Open”, “Save” and
“Close” buttons. This section describes how to put those buttons into
the window.</p>
<figure>
<img src="image/screenshot_tfe2.png"
alt="Screenshot of the file editor" />
<figcaption aria-hidden="true">Screenshot of the file
editor</figcaption>
</figure>
<p>The screenshot above shows the layout. The function
<code>app_open</code> in the source code <code>tfe2.c</code> is as
follows.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
tfe/tfe2.c app_open @@@</p>
<p>The function <code>app_open</code> builds the widgets in the main
application window.</p>
<ul>
<li>25-27: Creates a GtkApplicationWindow instance and sets the title
and default size.</li>
<li>29-30: Creates a GtkBox instance <code>boxv</code>. It is a vertical
box and a child of GtkApplicationWindow. It has two children. The first
child is a horizontal box. The second child is a GtkNotebook.</li>
<li>32-33: Creates a GtkBox instance <code>boxh</code> and appends it to
<code>boxv</code> as a first child.</li>
<li>35-40: Creates three dummy labels. The labels <code>dmy1</code> and
<code>dmy3</code> has a character width of ten. The other label
<code>dmy2</code> has hexpand property which is set to be TRUE. This
makes the label expands horizontally as long as possible.</li>
<li>41-44: Creates four buttons.</li>
<li>46-52: Appends these GtkLabel and GtkButton to
<code>boxh</code>.</li>
<li>54-57: Creates a GtkNotebook instance and sets hexpand and vexpand
properties to be TRUE. This makes it expand horizontally and vertically
as big as possible. It is appended to <code>boxv</code> as the second
child.</li>
</ul>
<p>The number of widget-build lines is 33(=57-25+1). We also needed many
variables (<code>boxv</code>, <code>boxh</code>, <code>dmy1</code>, …)
and most of them used only for building the widgets. Are there any good
solution to reduce these work?</p>
<p>Gtk provides GtkBuilder. It reads user interface (UI) data and builds
a window. It reduces this cumbersome work.</p>
<h2 id="the-ui-file">The UI File</h2>
<p>Look at the UI file <code>tfe3.ui</code> that defines widget
structure.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
tfe/tfe3.ui @@@</p>
<p>The is a XML file. Tags begin with <code>&lt;</code> and end with
<code>&gt;</code>. There are two types of tags, the start tag and the
end tag. For example, <code>&lt;interface&gt;</code> is a start tag and
<code>&lt;/interface&gt;</code> is an end tag. The UI file begins and
ends with interface tags. Some tags, for example object tags, can have a
class and id attributes in their start tag.</p>
<ul>
<li>1: XML declaration. It specifies that the XML version is 1.0 and the
encoding is UTF-8.</li>
<li>3-6: An object tag with <code>GtkApplicationWindow</code> class and
<code>win</code> id. This is the top level window. And the three
properties of the window are defined. The <code>title</code> property is
“file editor”, <code>default-width</code> property is 600 and
<code>default-height</code> property is 400.</li>
<li>7: child tag means a child widget. For example, line 7 tells us that
GtkBox object with “boxv” id attribute is a child widget of
<code>win</code>.</li>
</ul>
<p>Compare this ui file and the lines 25-57 in the <code>tfe2.c</code>
source code. Both builds the same window with its descendant
widgets.</p>
<p>You can check the ui file with <code>gtk4-builder-tool</code>.</p>
<ul>
<li><code>gtk4-builder-tool validate &lt;ui file name&gt;</code>
validates the ui file. If the ui file includes some syntactical error,
<code>gtk4-builder-tool</code> prints the error.</li>
<li><code>gtk4-builder-tool simplify &lt;ui file name&gt;</code>
simplifies the ui file and prints the result. If <code>--replace</code>
option is given, it replaces the ui file with the simplified one. If the
ui file specifies a value of property but it is default, then it will be
removed. And some values are simplified. For example, “TRUE”and “FALSE”
becomes “1” and “0” respectively. However, “TRUE” or “FALSE” is better
for maintenance.</li>
</ul>
<p>It is a good idea to check your ui file before compiling.</p>
<h2 id="gtkbuilder">GtkBuilder</h2>
<p>GtkBuilder builds widgets based on a ui file.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>GtkBuilder <span class="op">*</span>build<span class="op">;</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>build <span class="op">=</span> gtk_builder_new_from_file <span class="op">(</span><span class="st">&quot;tfe3.ui&quot;</span><span class="op">);</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a>win <span class="op">=</span> GTK_WIDGET <span class="op">(</span>gtk_builder_get_object <span class="op">(</span>build<span class="op">,</span> <span class="st">&quot;win&quot;</span><span class="op">));</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>gtk_window_set_application <span class="op">(</span>GTK_WINDOW <span class="op">(</span>win<span class="op">),</span> GTK_APPLICATION <span class="op">(</span>app<span class="op">));</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>nb <span class="op">=</span> GTK_WIDGET <span class="op">(</span>gtk_builder_get_object <span class="op">(</span>build<span class="op">,</span> <span class="st">&quot;nb&quot;</span><span class="op">));</span></span></code></pre></div>
<p>The function <code>gtk_builder_new_from_file</code> reads the file
given as an argument. Then, it builds the widgets and creates GtkBuilder
object. The function <code>gtk_builder_get_object (build, "win")</code>
returns the pointer to the widget <code>win</code>, which is the id in
the ui file. All the widgets are connected based on the parent-children
relationship described in the ui file. We only need <code>win</code> and
<code>nb</code> for the program below. This reduces lines in the C
source file.</p>
<p>@@<span class="citation" data-cites="shell">@shell</span> cd tfe;
diff tfe2.c tfe3.c @@@</p>
<p><code>60,103c61,65</code> means 44 (=103-60+1) lines are changed to 5
(=65-61+1) lines. Therefore, 39 lines are reduced. Using ui file not
only shortens C source files, but also makes the widgets’ structure
clear.</p>
<p>Now I’ll show you <code>app_open</code> function in the C file
<code>tfe3.c</code>.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
tfe/tfe3.c app_open @@@</p>
<p>The whole source code of <code>tfe3.c</code> is stored in src/tfe
directory.</p>
<h3 id="using-ui-string">Using ui string</h3>
<p>GtkBuilder can build widgets with string. Use
<code>gtk_builder_new_from_string</code> instead of
<code>gtk_builder_new_from_file</code>.</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="dt">char</span> <span class="op">*</span>uistring<span class="op">;</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>uistring <span class="op">=</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="st">&quot;&lt;interface&gt;&quot;</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a>  <span class="st">&quot;&lt;object class=&quot;</span>GtkApplicationWindow<span class="st">&quot; id=&quot;</span>win<span class="st">&quot;&gt;&quot;</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;&lt;property name=</span><span class="sc">\&quot;</span><span class="st">title</span><span class="sc">\&quot;</span><span class="st">&gt;file editor&lt;/property&gt;&quot;</span></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;&lt;property name=</span><span class="sc">\&quot;</span><span class="st">default-width</span><span class="sc">\&quot;</span><span class="st">&gt;600&lt;/property&gt;&quot;</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;&lt;property name=</span><span class="sc">\&quot;</span><span class="st">default-height</span><span class="sc">\&quot;</span><span class="st">&gt;400&lt;/property&gt;&quot;</span></span>
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;&lt;child&gt;&quot;</span></span>
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a>      <span class="st">&quot;&lt;object class=</span><span class="sc">\&quot;</span><span class="st">GtkBox</span><span class="sc">\&quot;</span><span class="st"> id=</span><span class="sc">\&quot;</span><span class="st">boxv</span><span class="sc">\&quot;</span><span class="st">&gt;&quot;</span></span>
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a>        <span class="st">&quot;&lt;property name=&quot;</span>orientation<span class="st">&quot;&gt;GTK_ORIENTATION_VERTICAL&lt;/property&gt;&quot;</span></span>
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a><span class="op">...</span> <span class="op">...</span> <span class="op">...</span></span>
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a><span class="op">...</span> <span class="op">...</span> <span class="op">...</span></span>
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a><span class="st">&quot;&lt;/interface&gt;&quot;</span><span class="op">;</span></span>
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a>build <span class="op">=</span> gtk_builder_new_from_string <span class="op">(</span>uistring<span class="op">,</span> <span class="op">-</span><span class="dv">1</span><span class="op">);</span></span></code></pre></div>
<p>This method has an advantage and disadvantage. The advantage is that
the ui string is written in the source code. So, no ui file is needed on
runtime. The disadvantage is that writing C string is a bit bothersome
because of the double quotes. If you want to use this method, you should
write a script that transforms ui file into C-string.</p>
<ul>
<li>Add backslash before each double quote.</li>
<li>Add double quotes at the left and right of the string in each
line.</li>
</ul>
<h3 id="gresource">Gresource</h3>
<p>Using Gresource is similar to using string. But Gresource is
compressed binary data, not text data. And there’s a compiler that
compiles ui file into Gresource. It can compile not only text files but
also binary files such as images, sounds and so on. And after
compilation, it bundles them up into one Gresource object.</p>
<p>An xml file is necessary for the resource compiler
<code>glib-compile-resources</code>. It describes resource files.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
tfe/tfe3.gresource.xml @@@</p>
<ul>
<li>2: <code>gresources</code> tag can include multiple gresources
(gresource tags). However, this xml has only one gresource.</li>
<li>3: The gresource has a prefix
<code>/com/github/ToshioCP/tfe3</code>.</li>
<li>4: The name of the gresource is <code>tfe3.ui</code>. The resource
will be pointed with <code>/com/github/ToshioCP/tfe3/tfe3.ui</code> by
GtkBuilder. The pattern is “prefix” + “name”. If you want to add more
files, insert them between line 4 and 5.</li>
</ul>
<p>Save this xml text to <code>tfe3.gresource.xml</code>. The gresource
compiler <code>glib-compile-resources</code> shows its usage with the
argument <code>--help</code>.</p>
<p>@@<span class="citation" data-cites="shell">@shell</span> LANG=C
glib-compile-resources –help @@@</p>
<p>Now run the compiler.</p>
<pre><code>$ glib-compile-resources tfe3.gresource.xml --target=resources.c --generate-source</code></pre>
<p>Then a C source file <code>resources.c</code> is generated. Modify
<code>tfe3.c</code> and save it as <code>tfe3_r.c</code>.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">&quot;resources.c&quot;</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="op">...</span> <span class="op">...</span> <span class="op">...</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="op">...</span> <span class="op">...</span> <span class="op">...</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a>build <span class="op">=</span> gtk_builder_new_from_resource <span class="op">(</span><span class="st">&quot;/com/github/ToshioCP/tfe3/tfe3.ui&quot;</span><span class="op">);</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="op">...</span> <span class="op">...</span> <span class="op">...</span></span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a><span class="op">...</span> <span class="op">...</span> <span class="op">...</span></span></code></pre></div>
<p>The function <code>gtk_builder_new_from_resource</code> builds
widgets from a resource.</p>
<p>Then, compile and run it. A window appears and it is the same as the
screenshot at the beginning of this page.</p>
<p>Generally, resource is the best way for C language. If you use other
languages like Ruby, string is better than resource.</p>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
  </body>
  </html>
